HOWTO Submit Patches to the FreeDOS FreeCOM and Kernel Projects

Version 1.0
Updated 4/29/99 John Price

Introduction

Both the FreeDOS kernel and FreeCom have a "history.txt" file where people that contribute to either project should add comments about what changes they have implemented. There are no strict guidelines for these files now, but you can look at the file to see how everyone else does it. Most people just include what changes they made (and why if necessary) and sometimes specify what files they changed.

When you create the patch file (see below) it will contain the changes to the history.txt file, as well as all the other changes you made. Then when I get it, I can read your entry in the history.txt file and see what all you did.

Making patch files:

The "diff" program referred to within is available for UN*X and DOS OS's. Both versions are available on the GCFL FTP site at ftp://ftp.gcfl.net/FreeDOS/tools.

The patch files I refer to are really just the output that the diff program creates. I call them that because I use a program called "patch" to merge your patch file into my source code. Sorry if this seems confusing.

Here is a description of the diff program from the GNU web page (http://www.gnu.org):

"You can use the 'diff' command to show differences between two files, or each corresponding file in two directories. 'diff' outputs differences between files line by line in any of several formats, selectable by command line options. This set of differences is often called a 'diff' or 'patch.' For files that are identical, 'diff' normally produces no output; for binary (non-text) files, 'diff' normally reports only that they are different."

Points to remember:

It is VERY important that you specify the name of the release (the version, i.e. com075a, or build 2010) that your patches were generated from!
You should always get the latest source code available. Patches submitted that are changes to old source code are no good to the project. If they are only a revision or two behind, then we can work with them, but it's usually a manual process (ouch!).
You should make a copy of the latest source code, and then change that code so that you will end up with two directories, an original directory (with the original source), and a new directory (with the original source plus all your revolutionary changes). This is not too important since you can always re-download the latest source code from the site, but who wants to download source twice?

These are the command line options I recommend for creating patch files for the FreeDOS project.

-r or --recursive: When comparing directories, recursively compare any subdirectories found.
-b or --ignore-space-change: Ignore changes in amount of white space.
-U 5 or --unified=5: Use the unified output format, showing 5 lines of context.
-d or --minimal: Change the algorithm to perhaps find a smaller set of changes.
-N or --new-file: In directory comparison, if a file is found in only one directory, treat it as present but empty in the other directory.
-w or --ignore-all-space: Ignore white space when comparing lines.
-B or --ignore-blank-lines: Ignore changes that just insert or delete blank lines

Example

If you have version 0.76b of FreeCom in the directory "FREECOM\ORIG", and a copy of the same source tree, but with your changes included, in a directory called "FREECOM\NEW", and you want to create a patch file called "patch.txt", then you need to change to the directory "FREECOM", and issue this command:

diff -bBdNrw -U5 ORIG NEW > patch.txt

Always put the original directory name first, then the new directory name.

You can upload your patches to ftp://ftp.gcfl.net/incoming and send an email to John Price (linux-guru@gcfl.net).

Unless otherwise stated, FD-DOC HOWTO documents are copyrighted by their respective authors. FD-DOC HOWTO documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions.

All translations, derivative works, or aggregate works incorporating any FD-DOC HOWTO documents must be covered under this copyright notice. That is, you may not produce a derivative work from a HOWTO and impose additional restrictions on its distribution. Exceptions to these rules may be granted under certain conditions; please contact the FD-DOC HOWTO coordinator at the address given below.

In short, we wish to promote dissemination of this information through as many channels as possible. However, we do wish to retain copyright on the HOWTO documents, and would like to be notified of any plans to redistribute the HOWTOs.

If you have any questions, please contact the FD-DOC coordinator at jhall1@isd.net.